---
layout: docs
page_title: AWS KMS
description: Manage the lifecycle of keys in AWS KMS with the Key Management secrets engine plugin.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# AWS KMS

@include 'alerts/enterprise-and-hcp.mdx'

AWS KMS secrets engine requires [Vault Enterprise](https://www.hashicorp.com/products/vault/pricing)
with the Advanced Data Protection (ADP) module.

The Key Management secrets engine supports lifecycle management of keys in [AWS KMS](https://aws.amazon.com/kms/)
regions. This is accomplished by configuring a KMS provider resource with the `awskms` provider and
other provider-specific parameter values.

The following sections describe how to properly configure the secrets engine to enable
the functionality.

## Authentication

The Key Management secrets engine must be configured with credentials that have sufficient
permissions to manage keys in an AWS KMS region. The authentication parameters are described
in the [credentials](/vault/api-docs/secret/key-management/awskms#credentials) section of the API
documentation. The authentication parameters will be set with the following order of
precedence:

1. [KMS provider credentials](/vault/api-docs/secret/key-management/awskms#credentials)
2. Environment variables
3. Shared credentials file
4. IAM role for AWS EC2 or ECS task

The IAM principal associated with the provided credentials must have the following minimum
[AWS KMS permissions](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html):

- `kms:CreateKey`
- `kms:GetParametersForImport`
- `kms:ImportKeyMaterial`
- `kms:EnableKey`
- `kms:DisableKey`
- `kms:ScheduleKeyDeletion`
- `kms:CreateAlias`
- `kms:UpdateAlias`
- `kms:DeleteAlias`
- `kms:ListAliases`
- `kms:TagResource`

## Configuration

The following is an example of how to configure the KMS provider resource using the Vault CLI:

```text
$ vault write keymgmt/kms/example-kms \
    provider="awskms" \
    key_collection="us-west-1" \
    credentials=access_key="ASIADJO3WTX6WPLJM42V" \
    credentials=secret_key="bCiYmNroLxLmPNQ47VIvjlm8mQu5oktZcQdq195w"
```

Refer to the AWS KMS [API documentation](/vault/api-docs/secret/key-management/awskms)
for a detailed description of individual configuration parameters.

## Key transfer specification

Keys are securely transferred from the secrets engine to AWS KMS regions in accordance
with the AWS KMS [Bring Your Own Key](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)
specification.

## Key rotation

AWS KMS keys with imported key material are not eligible for
[automatic key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
within AWS KMS. As such, key rotations performed by the secrets engine use the
[manual key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-manually)
process. Applications should refer to the [alias](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html)
associated with imported keys. Aliases will always have the form: `hashicorp/<key_name>-<unix_timestamp>`.

## Key purpose compatibility

The following table defines which key [purposes](/vault/api-docs/secret/key-management#purpose) can be used
for each key type supported by AWS KMS.

| Key Type       | Purpose                 |
| -------------- | ----------------------- |
| `aes256-gcm96` | `encrypt` and `decrypt` |
